PCGateway

The miniHIL currently uses the USB port together with the winUSB driver and a proprietary multichannel protocol to connect to the miniHIL software running on the PC. To allow easier integration with existing tools/debuggers/APIs we provide two options which allow the test cases and actors to communicate with custom software running on the PC.

Option one is the so called "whitebox test interface". It provides a predefined set of messages which can be used to communicate between the miniHIL and a PC application.

The second option is to use the "multi channel pass through" functionality. This provides an interface to forward blobs of bytes between a miniHIL actor and a tcp socket on the PC. The structure of the passed data is completely free and has to be adapted to the users requirement.

Note A normal PC (with Windows) is not realtime capable. Therefore, no realtime guarantees can be given for the interaction of actors and test cases with the PC. This does not influence the realtime behavior of actors which do not depend on the PC connection (i.e. which are executed on the miniHIL processor).
Note This documentation page is work in progress. Please contact us if you have any questions.

The "whitebox test" interface

The whitebox test interface consists of two parts:

  • The miniHIL API

  • The miniHIL whitebox PC application

While the miniHIL API may be used with a custom PC application, that is not recommended.

The "whitebox" miniHIL API

The miniHIL API provides three C-functions which may be used in actor or cage target/action code to send messages to the PC software:

/*
* Instruct the PC application to read a 1, 2 or 4 byte int from the provided symbol name and compare the read value to the passed value.
* Values are read using a pyocd compatible debugger connected to the target
* In case of a match the PC application will send a "done" message with payload == 0.
* In case of a value mismatch the payload will be == 1.
* Negative payloads are returned for other errors.
*/
void Wb_expectInt(const char* name, int64_t value);

/*
* Instruct the PC application to write a 1, 2 or 4 byte int value to the provided symbol name.
* Values are written using a pyocd compatible debugger connected to the target.
* If the value could be written the PC application will send a "done" message with payload == 0.
* Negative payloads are returned for errors.
*/
void Wb_setInt(const char* name, int64_t value);

/*
* Instruct the PC application to call a custom script. The script to call is identified by the passed name.
* The parameter value will be forwarded to the custom script.
* The custom script must return a "done" message. The payload depends on the users script.
*/
void Wb_runCustom(const char* name, const char* parameter);

In addition the miniHIL API provides an actor which decodes PC messages and provides them via a port: whitebox.api.whitebox.AWhiteboxRemote.

Once added to your miniHIL project you can connect the actors whitebox port (Protocol: PWhiteboxRemote) to your test actor or any other custom actor. You can then use the incoming "done" messages in cage reaction blocks or state machine transitions.

The "whitebox" PC application

The miniHILLib contains a basic python application in the minihillib/scripts/whitebox subfolder. This application is not meant to be run directly but through the runWhiteboxClient gradle command which will configure the required python interpreter and search paths.

Initial configuration

To be able to run the PC application some configuration is needed:

  • Download the CMSIS Pack for your target controller. Most packs can be found here: https://developer.arm.com/tools-and-software/embedded/cmsis/cmsis-packs

    • Store the pack in any folder (you can configure the path later)

  • Configure your project whitebox configuration folder:

    • Create a new folder next to your gradle.properties file.

    • Add a whitebox_path=myFolderName entry to the gradle.properties file (the folder name is resolved relative to the gradle.properties file)

    • In the newly created folder add a config.ini file with the following content and configure your project:

[tools]
# Path to your packs folder
packs = ../../../../packs

[SUT]
# Path to your elf file. Also accepts .axf files and any other file format supported by pyocd.
elfFile = ../DUTProject/Build/target.elf
# or: elfFile = ../DUTProject/Build/target.axf

Additional ini options

option description

[debugger].serial

debugger serial number to connect to in case multiple debuggers are connected to the PC

[debugger].enabled

can be set to true or false to completely disable the built-in pyocd debugger interface. This can be used in case the target debugger is not compatible. You can then skip the packs and elf file configuration.

Adding custom commands / scripts